Terraform で API Gateway（REST API）を構築する
今回は Terraform で API Gateway を構築する機会がありましたので、ハマりポイントなどを含めて紹介いたします。
Terraform で作る API Gateway 環境
今回の環境ですが、以下のような構成を想定しています。API Gateway のバックエンドは NLB を経由して ECS タスクへとリクエストが流れます。本記事で作成するのは、枠で囲んだ部分です。
もう少し詳細にご紹介すると、この記事をとおして Terraform で構築する API Gateway は以下のとおり。認証なども特に設定していない簡易的なものです。
- API Gateway
- REST API
- メソッドおよびインテグレーション（OpenAPI でインポート）
- ステージ
- デプロイ
- リソースポリシー（OpenAPI でインポート）
- VPC リンク
- カスタムドメイン
- ベースパスマッピング
一方、以下のリソースはリソース参照部分の記載がありますが、既にあるものとして仮定しています。（参照先のリソース作成部分のコードは記載していません）
- NLB
- Route53
実行環境
今回、検証で利用した実行環境は下記のとおりです。
$ terraform version Terraform v0.12.29 + provider.aws v3.5.0
Terraform で API Gateway を構築するぞ！
VPC リンクの作成
はじめに、今回は VPC 内の ECS コンテナにリクエストを送るため、VPC リンクを作成します。REST API で VPC リンクに利用できる ELB は NLB のみです。
resource "aws_api_gateway_vpc_link" "vpclink" {
name = "vpc_link"
target_arns = [aws_lb.nlb.arn]
}
OpenAPI ファイルの準備（メソッドおよびインテグレーションの定義）
メソッドやインテグレーションの作成は aws_api_gateway_method および aws_api_gateway_integration など Terraform（HCL） で書くこともできますが、今回は OpenAPI を事前に作成しておきインポートする方法で構築します。
以下は / に対して GET メソッドおよび、VPC リンク先へのプロキシを定義した、とても単純な OpenAPI の定義ファイルです。OpenAPI 仕様に対する API Gateway 拡張は x-amazon-apigateway-xxx で記述します。詳細は公式ガイドを参照ください。
openapi: "3.0.1"
info:
title: "test_api"
version: "2020-09-09T06:11:13Z"
paths:
/:
get:
responses:
200:
description: "200 response"
content:
application/json:
schema:
$ref: "#/components/schemas/Empty"
x-amazon-apigateway-integration:
uri: "${nlb_uri}"
responses:
default:
statusCode: "200"
passthroughBehavior: "when_no_match"
connectionType: "VPC_LINK"
connectionId: "${vpc_link}"
httpMethod: "GET"
type: "http_proxy"
上記 .yaml ファイルを aws_api_gateway_rest_api が参照するためデータリソースとして定義します。vars で環境変数を渡すことも可能です。今回は VPC リンク ID および、NLB の URI を環境変数に指定しました。
data "template_file" "openapi" {
template = "${file("./OpenAPI/test_api-dev-apigateway.yaml")}"
vars = {
vpc_link = aws_api_gateway_vpc_link.vpclink.id
nlb_uri = "http://${aws_lb.nlb.dns_name}"
}
}
構築後の API Gateway からエクスポートした .yaml ファイルを再利用する場合は ${} 部分が実際の値に置き換わっているのでご注意ください。
REST API 定義
先程の template_file を指定して、REST API を定義します。name は OpenAPI 内の title に置き換えられますが差があると毎回 terraform plan の差分になってしまうので揃えます。今回は REGIONAL エンドポイントで作成しています。
resource "aws_api_gateway_rest_api" "api" {
name = "test_api"
body = data.template_file.openapi.rendered
endpoint_configuration {
types = ["REGIONAL"]
}
lifecycle {
ignore_changes = [
policy
]
}
}
本記事ではリソースポリシーを後ほど OpenAPI 内で定義する手順となっています。Terraform（HCL）では記述しないため、ポリシー定義後に設定差分として検出されないように ignore_changes に指定しておきます。
ステージとデプロイメント定義
ステージの定義は aws_api_gateway_stage リソースがありますが、aws_api_gateway_deployment だけの指定でも stage_name に基づいてステージが作成されます。
アクセスログ、キャッシュ、X-Ray トレーシングなどなど、ステージの詳細設定が必要であれば aws_api_gateway_stage を個別に定義してください。今回は簡易設定として、aws_api_gateway_deployment のみで定義しています。
resource "aws_api_gateway_deployment" "deployment" {
depends_on = [aws_api_gateway_rest_api.api]
rest_api_id = aws_api_gateway_rest_api.api.id
stage_name = "dev"
triggers = {
redeployment = "v0.1"
}
lifecycle {
create_before_destroy = true
}
}
今回のキモは triggers と create_before_destroy です。
triggers
OpenAPI の内容や、その他 REST API 設定を変更し terraform apply すると定義情報は更新されますが再デプロイはされません。再デプロイをトリガーするための設定が triggers = {redeployment = "xxx"} になります。
上記の例では単純に v0.1 のような値を与えていますので、v0.2に変更すると再デプロイがトリガーされます。
いちいち値を変更するのが面倒だしスマートじゃない、という場合は .tf や OpenAPI ファイルのハッシュ値を指定することもできます。ファイル内容の変更によってハッシュ値が変わりますので、わざわざ値を変更せずとも再デプロイをトリガーします。
triggers = {
redeployment = sha1(file("./OpenAPI/xxx.yaml"))
}
create_before_destroy
create_before_destroy は既存のリソースがあった場合に、先に削除してから作り直すことを指示します。
ベースパスマッピングを利用していない場合、この指定がなくても再デプロイはうまく動作しますが、ベースパスマッピングがある場合、create_before_destroy の指定がないと、以下のようなエラーになります。
Error: error deleting API Gateway Deployment (xxxxxx): BadRequestException: Active stages pointing to this deployment must be moved or deleted
リソースポリシー定義
リソースポリシーは data "aws_iam_policy_document" を使って定義することも出来ますが、今回は OpenAPI 内で x-amazon-apigateway-policy を追加し、再デプロイで設定することにしました。（参考:x-amazon-apigateway-policy）
初回のデプロイ後、execution_arn が確定しますので、以下のような記述で API Gateway の呼び出し元を制限することができます。
（最下行に追加）
x-amazon-apigateway-policy:
Version: "2012-10-17"
Statement:
- Sid: ""
Effect: "Allow"
Principal:
AWS: "*"
Action: "execute-api:Invoke"
Resource: "arn:aws:execute-api:ap-northeast-1:123456789012:7c7dxz6gh7/*"
Condition:
IpAddress:
aws:SourceIp:
- "58.xx.xx.xx/32"
カスタムドメイン定義
カスタムドメインに使用するドメインおよび、ACM 証明書は別途、設定されていることを前提とします。ちなみに、今回は REGIONAL ですので ACM 証明書は対象リージョンの東京に作成済みです。EDGE の場合は CloudFront 同様にバージニアで作成してください。
resource "aws_api_gateway_domain_name" "domain" {
domain_name = "api.marumo.classmethod.info"
regional_certificate_arn = aws_acm_certificate_validation.retrieval.certificate_arn
endpoint_configuration {
types = ["REGIONAL"]
}
}
Terraform で ACM 無料証明書発行される場合は、以下の記事を参照ください。
ベースパスマッピング定義
aws_api_gateway_domain_name ではカスタムドメインを定義しただけです。次にベースパスマッピングを定義し、カスタムドメインと呼び出し先のステージを紐付けます。
resource "aws_api_gateway_base_path_mapping" "base_path" {
depends_on = [aws_api_gateway_deployment.deployment]
api_id = aws_api_gateway_rest_api.api.id
stage_name = aws_api_gateway_deployment.deployment.stage_name
domain_name = aws_api_gateway_domain_name.domain.domain_name
}
動作確認
上記のとおり Terraform で作成した API Gateway をコールして動作確認してみましょう。まずは、リソースポリシーで許可されたアクセス元からの API コール。
$ curl https://checkip.amazonaws.com/ 58.xx.xx.xx $ curl https://api.marumo.classmethod.info/ Hello,Classmethod!
次に、許可されていないアクセス元からの API コール。
$ curl https://checkip.amazonaws.com/
54.xx.xx.xx
$ curl https://api.marumo.classmethod.info/
{"Message":"User: anonymous is not authorized to perform: execute-api:Invoke on resource: arn:aws:execute-api:ap-northeast-1:********3583:7c7dxz6gh7/dev/GET/"}
期待したとおりの動きですね。これでアクセス元を制限した REST API を Terraform でデプロイできるこを確認できました。
さいごに
API Gateway の IaC には AWS SAM や Serverless Framework、最近だと CDK あたりを利用されることが多いとは思います。適材適所で IaC のツールを使い分けるのが正解だとは思いますが、とはいえ、これから IaC をはじめる方にとって幾つものツールをリソース毎に使い分けるには学習コストもそれなりに高くなるでしょう。
正直、Terraform で API Gateway を構築、運用する情報はあまり多くないのですが、「ようやく手に馴染んできた Terraform で出来る限り管理したいんや！」という方も少なくないかと思いましたので試してみました。
今回はかなりシンプルな API Gateway 定義しかしていないため、判断するには難しいですが触ってみた感じでは Terraform でも十分に管理できるんじゃないか、という気がいたします。もちろん先に述べたようなツールと比較するとコード量は多いのですが。。
（「いやいや、やってみたけどココが辛かった」「おい、やめとけ。そっちは修羅の国やぞ」という知見をお持ちの方がおられましたらフィードバックください！）
以上！大阪オフィスの丸毛（@marumo1981）でした！
サンプル
./OpenAPI/rest_api-dev-apigateway.yaml
openapi: "3.0.1"
info:
title: "test_api"
version: "2020-09-09T06:11:13Z"
paths:
/:
get:
responses:
200:
description: "200 response"
content:
application/json:
schema:
$ref: "#/components/schemas/Empty"
x-amazon-apigateway-integration:
uri: "${nlb_uri}"
responses:
default:
statusCode: "200"
passthroughBehavior: "when_no_match"
connectionType: "VPC_LINK"
connectionId: "${vpc_link}"
httpMethod: "GET"
type: "http_proxy"
x-amazon-apigateway-policy:
Version: "2012-10-17"
Statement:
- Sid: ""
Effect: "Allow"
Principal:
AWS: "*"
Action: "execute-api:Invoke"
Resource: "arn:aws:execute-api:ap-northeast-1:123456789012:7c7dxz6gh7/*"
Condition:
IpAddress:
aws:SourceIp:
- "58.xx.xx.xx/32"
./api-gateway.tf
resource "aws_api_gateway_vpc_link" "vpclink" {
name = "vpc_link"
target_arns = [aws_lb.nlb.arn]
}
data "template_file" "openapi" {
template = "${file("./OpenAPI/test_api-dev-apigateway.yaml")}"
vars = {
vpc_link = aws_api_gateway_vpc_link.vpclink.id
nlb_uri = "http://${aws_lb.nlb.dns_name}"
}
}
resource "aws_api_gateway_rest_api" "api" {
name = "test_api"
body = data.template_file.openapi.rendered
endpoint_configuration {
types = ["REGIONAL"]
}
lifecycle {
ignore_changes = [
policy
]
}
}
resource "aws_api_gateway_deployment" "deployment" {
depends_on = [aws_api_gateway_rest_api.api]
rest_api_id = aws_api_gateway_rest_api.api.id
stage_name = "dev"
triggers = {
redeployment = "v0.1"
}
lifecycle {
create_before_destroy = true
}
}
resource "aws_api_gateway_domain_name" "domain" {
domain_name = "api.marumo.classmethod.info"
regional_certificate_arn = aws_acm_certificate_validation.retrieval.certificate_arn
endpoint_configuration {
types = ["REGIONAL"]
}
}
resource "aws_api_gateway_base_path_mapping" "base_path" {
depends_on = [aws_api_gateway_deployment.deployment]
api_id = aws_api_gateway_rest_api.api.id
stage_name = aws_api_gateway_deployment.deployment.stage_name
domain_name = aws_api_gateway_domain_name.domain.domain_name
}
